.TH "IRC commands: channel management." 3 "10 Jan 2009" "Version 1.3" "libircclient" \" -*- nroff -*-
.ad l
.nh
.SH NAME
IRC commands: channel management. \- 
.SS "Functions"

.in +1c
.ti -1c
.RI "int \fBirc_cmd_join\fP (\fBirc_session_t\fP *session, const char *channel, const char *key)"
.br
.RI "\fIJoins the new IRC channel. \fP"
.ti -1c
.RI "int \fBirc_cmd_part\fP (\fBirc_session_t\fP *session, const char *channel)"
.br
.RI "\fILeaves the IRC channel. \fP"
.ti -1c
.RI "int \fBirc_cmd_invite\fP (\fBirc_session_t\fP *session, const char *nick, const char *channel)"
.br
.RI "\fIInvites a user to invite-only channel. \fP"
.ti -1c
.RI "int \fBirc_cmd_names\fP (\fBirc_session_t\fP *session, const char *channel)"
.br
.RI "\fIObtains a list of users who're in channel. \fP"
.ti -1c
.RI "int \fBirc_cmd_list\fP (\fBirc_session_t\fP *session, const char *channel)"
.br
.RI "\fIObtains a list of active server channels with their topics. \fP"
.ti -1c
.RI "int \fBirc_cmd_topic\fP (\fBirc_session_t\fP *session, const char *channel, const char *topic)"
.br
.RI "\fIViews or changes the channel topic. \fP"
.ti -1c
.RI "int \fBirc_cmd_channel_mode\fP (\fBirc_session_t\fP *session, const char *channel, const char *mode)"
.br
.RI "\fIViews or changes the channel mode. \fP"
.ti -1c
.RI "int \fBirc_cmd_kick\fP (\fBirc_session_t\fP *session, const char *nick, const char *channel, const char *reason)"
.br
.RI "\fIKick some lazy ass out of channel. \fP"
.in -1c
.SH "Function Documentation"
.PP 
.SS "int irc_cmd_channel_mode (\fBirc_session_t\fP * session, const char * channel, const char * mode)"
.PP
Views or changes the channel mode. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP An initiated and connected session. 
.br
\fIchannel\fP A channel name to invite to. Must not be NULL. 
.br
\fImode\fP A channel mode, described below. If NULL, the channel mode is not changed, just the old mode is returned.
.RE
.PP
\fBReturns:\fP
.RS 4
Return code 0 means success. Other value means error, the error code may be obtained through \fBirc_errno()\fP. Any error, generated by the IRC server, is available through \fBirc_callbacks_t::event_numeric\fP.
.RE
.PP
The \fBirc_cmd_channel_mode()\fP is used to change or view the channel modes. The \fIchannel\fP mode is returned if the \fImode\fP is NULL. If the \fImode\fP is not NULL, the mode for the \fIchannel\fP will be changed. Note that, only channel operators can change the channel modes.
.PP
Channel mode is represended by the letters combination. Every letter has its own meaning in channel modes. Most channel mode letters are boolean (i.e. could only be set or reset), but a few channel mode letters accept a parameter. All channel options are set by adding a plus sign before the letter, and reset by adding a minus sign before the letter.
.PP
Here is the list of 'standard' channel modes:
.PP
.IP "\(bu" 2
\fIo\fP \fInickname\fP - gives (+o nick) or takes (-o nick) the channel operator privileges from a \fInickname\fP. This mode affects the users in channel, not the channel itself. Examples: '+o tim', '-o watson'.
.PP
.PP
.IP "\(bu" 2
\fIp\fP - sets (+p) or resets (-p) private channel flag. Private channels are shown in channel list as 'Prv', without the topic.
.PP
.PP
.IP "\(bu" 2
\fIs\fP - sets (+p) or resets (-p) secret channel flag. Secret channels aren't shown in channel list at all.
.PP
.PP
.IP "\(bu" 2
\fIi\fP - sets (+i) or resets (-i) invite-only channel flag. When the flag is set, only the people who are invited by \fBirc_cmd_invite()\fP, can join this channel.
.PP
.PP
.IP "\(bu" 2
\fIt\fP - sets (+t) or resets (-t) topic settable by channel operator only flag. When the flag is set, only the channel operators can change the channel topic.
.PP
.PP
.IP "\(bu" 2
\fIn\fP - sets (+n) or resets (-n) the protection from the clients outside the channel. When the \fI+n\fP mode is set, only the clients, who are in channel, can send the messages to the channel.
.PP
.PP
.IP "\(bu" 2
\fIm\fP - sets (+m) or resets (-m) the moderation of the channel. When the moderation mode is set, only channel operators and the users who have the \fI+v\fP user mode can speak in the channel.
.PP
.PP
.IP "\(bu" 2
\fIv\fP \fInickname\fP - gives (+v nick) or takes (-v nick) from user the ability to speak on a moderated channel. Examples: '+v tim', '-v watson'.
.PP
.PP
.IP "\(bu" 2
\fIl\fP \fInumber\fP - sets (+l 20) or removes (-l) the restriction of maximum users in channel. When the restriction is set, and there is a number of users in the channel, no one can join the channel anymore.
.PP
.PP
.IP "\(bu" 2
\fIk\fP \fIkey\fP - sets (+k secret) or removes (-k) the password from the channel. When the restriction is set, any user joining the channel required to provide a channel key.
.PP
.PP
.IP "\(bu" 2
\fIb\fP \fImask\fP - sets (+b *!*@*.mil) or removes (-b *!*@*.mil) the ban mask on a user to keep him out of channel. Note that to remove the ban you must specify the ban mask to remove, not just '-b'.
.PP
.PP
Note that the actual list of channel modes depends on the IRC server, and can be bigger. If you know the popular channel modes, which aren't mentioned here - please contact me at tim@krasnogorsk.ru
.PP
Possible error responces for this command from the RFC1459:
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NEEDMOREPARAMS\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_CHANOPRIVSNEEDED\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NOSUCHNICK\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NOTONCHANNEL\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_KEYSET\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_UNKNOWNMODE\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NOSUCHCHANNEL\fP
.PP
.PP
And the mode information is given using following reply codes:
.IP "\(bu" 2
\fBLIBIRC_RFC_RPL_CHANNELMODEIS\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_RPL_BANLIST\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_RPL_ENDOFBANLIST\fP
.PP
.PP
\fBSee also:\fP
.RS 4
\fBirc_cmd_topic\fP \fBirc_cmd_list\fP 
.RE
.PP

.SS "int irc_cmd_invite (\fBirc_session_t\fP * session, const char * nick, const char * channel)"
.PP
Invites a user to invite-only channel. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP An initiated and connected session. 
.br
\fInick\fP A nick to invite. Must not be NULL. 
.br
\fIchannel\fP A channel name to invite to. Must not be NULL.
.RE
.PP
\fBReturns:\fP
.RS 4
Return code 0 means success. Other value means error, the error code may be obtained through \fBirc_errno()\fP. Any error, generated by the IRC server, is available through \fBirc_callbacks_t::event_numeric\fP.
.RE
.PP
This function is used to invite someone to invite-only channel. 'Invite-only' is a channel mode, which restricts anyone, except invided, to join this channel. After invitation, the user could join this channel. The user, who is invited, will receive the \fBirc_callbacks_t::event_invite\fP event. Note that you must be a channel operator to INVITE the users.
.PP
Possible error responces for this command from the RFC1459:
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NEEDMOREPARAMS\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NOSUCHNICK\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NOTONCHANNEL\fP
.IP "\(bu" 2
LIBIRC_RFC_ERR_ERR_USERONCHANNEL
.IP "\(bu" 2
LIBIRC_RFC_ERR_ERR_CHANOPRIVSNEEDED
.PP
.PP
And on success one of the following replies returned:
.IP "\(bu" 2
\fBLIBIRC_RFC_RPL_INVITING\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_RPL_AWAY\fP
.PP
.PP
\fBSee also:\fP
.RS 4
\fBirc_callbacks_t::event_invite\fP \fBirc_cmd_channel_mode\fP 
.RE
.PP

.SS "int irc_cmd_join (\fBirc_session_t\fP * session, const char * channel, const char * key)"
.PP
Joins the new IRC channel. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP An initiated and connected session. 
.br
\fIchannel\fP A channel name to join to. Must not be NULL. 
.br
\fIkey\fP Channel password. May be NULL.
.RE
.PP
\fBReturns:\fP
.RS 4
Return code 0 means success. Other value means error, the error code may be obtained through \fBirc_errno()\fP. Any error, generated by the IRC server, is available through \fBirc_callbacks_t::event_numeric\fP.
.RE
.PP
This function is used to JOIN the IRC channel. If the channel is not exist, it will be automatically created by the IRC server. Note that to JOIN the password-protected channel, you must know the password, and specify it in the \fIkey\fP argument.
.PP
If join is successful, the \fBirc_callbacks_t::event_join\fP is called (with \fIorigin\fP == your nickname), then you are sent the channel's topic (using \fBLIBIRC_RFC_RPL_TOPIC\fP) and the list of users who are on the channel (using \fBLIBIRC_RFC_RPL_NAMREPLY\fP), which includes the user joining - namely you.
.PP
Possible error responces for this command from the RFC1459:
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NEEDMOREPARAMS\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_BANNEDFROMCHAN\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_INVITEONLYCHAN\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_BADCHANNELKEY\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_CHANNELISFULL\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_BADCHANMASK\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NOSUCHCHANNEL\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_TOOMANYCHANNELS\fP
.PP
.PP
And on success the following replies returned:
.IP "\(bu" 2
\fBLIBIRC_RFC_RPL_TOPIC\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_RPL_NAMREPLY\fP 
.PP

.SS "int irc_cmd_kick (\fBirc_session_t\fP * session, const char * nick, const char * channel, const char * reason)"
.PP
Kick some lazy ass out of channel. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP An initiated and connected session. 
.br
\fInick\fP A nick to kick. Must not be NULL. 
.br
\fIchannel\fP A channel to kick this nick out of. Must not be NULL. 
.br
\fIreason\fP A reason to kick. May be NULL.
.RE
.PP
\fBReturns:\fP
.RS 4
Return code 0 means success. Other value means error, the error code may be obtained through \fBirc_errno()\fP. Any error, generated by the IRC server, is available through \fBirc_callbacks_t::event_numeric\fP.
.RE
.PP
This function is used to kick a person out of channel. Note that you must be a channel operator to kick anyone.
.PP
Possible error responces for this command from the RFC1459:
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NEEDMOREPARAMS\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_BADCHANMASK\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NOSUCHCHANNEL\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NOTONCHANNEL\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_CHANOPRIVSNEEDED\fP
.PP
.PP
On success the \fBirc_callbacks_t::event_kick\fP event will be generated.
.PP
\fBSee also:\fP
.RS 4
\fBirc_callbacks_t::event_numeric\fP 
.RE
.PP

.SS "int irc_cmd_list (\fBirc_session_t\fP * session, const char * channel)"
.PP
Obtains a list of active server channels with their topics. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP An initiated and connected session. 
.br
\fIchannel\fP A channel name(s) to list. May be NULL, in which case all the channels will be listed. It is possible to specify more than a single channel, but several channel names should be separated by a comma.
.RE
.PP
\fBReturns:\fP
.RS 4
Return code 0 means success. Other value means error, the error code may be obtained through \fBirc_errno()\fP. Any error, generated by the IRC server, is available through \fBirc_callbacks_t::event_numeric\fP.
.RE
.PP
This function is used to ask the IRC server for the active (existing) channels list. The list will be returned using LIBIRC_RFC_RPL_LISTSTART - \fBLIBIRC_RFC_RPL_LIST\fP - \fBLIBIRC_RFC_RPL_LISTEND\fP sequence. Note that 'private' channels are listed (without their topics) as channel 'Prv' unless the client generating the LIST query is actually on that channel. Likewise, secret channels are not listed at all unless the client is a member of the channel in question.
.PP
Possible error responces for this command from the RFC1459:
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NOSUCHSERVER\fP
.PP
.PP
And the channel list is returned using the following reply codes:
.IP "\(bu" 2
LIBIRC_RFC_RPL_LISTSTART
.IP "\(bu" 2
\fBLIBIRC_RFC_RPL_LISTEND\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_RPL_LIST\fP 
.PP

.SS "int irc_cmd_names (\fBirc_session_t\fP * session, const char * channel)"
.PP
Obtains a list of users who're in channel. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP An initiated and connected session. 
.br
\fIchannel\fP A channel name(s) to obtain user list. Must not be NULL. It is possible to specify more than a single channel, but several channel names should be separated by a comma.
.RE
.PP
\fBReturns:\fP
.RS 4
Return code 0 means success. Other value means error, the error code may be obtained through \fBirc_errno()\fP. Any error, generated by the IRC server, is available through \fBirc_callbacks_t::event_numeric\fP.
.RE
.PP
This function is used to ask the IRC server for the list of the users who're in specified channel. You can list all nicknames that are visible to you on any channel that you can see. The list of users will be returned using RPL_NAMREPLY and RPL_ENDOFNAMES numeric codes.
.PP
The channel names are returned by \fBirc_callbacks_t::event_numeric\fP using the following reply codes:
.IP "\(bu" 2
\fBLIBIRC_RFC_RPL_NAMREPLY\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_RPL_ENDOFNAMES\fP 
.PP

.SS "int irc_cmd_part (\fBirc_session_t\fP * session, const char * channel)"
.PP
Leaves the IRC channel. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP An initiated and connected session. 
.br
\fIchannel\fP A channel name to leave. Must not be NULL.
.RE
.PP
\fBReturns:\fP
.RS 4
Return code 0 means success. Other value means error, the error code may be obtained through \fBirc_errno()\fP. Any error, generated by the IRC server, is available through \fBirc_callbacks_t::event_numeric\fP.
.RE
.PP
This function is used to leave the IRC channel you've already joined to. An attempt to leave the channel you aren't in results a \fBLIBIRC_RFC_ERR_NOTONCHANNEL\fP server error.
.PP
Possible error responces for this command from the RFC1459:
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NEEDMOREPARAMS\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NOSUCHCHANNEL\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NOTONCHANNEL\fP 
.PP

.SS "int irc_cmd_topic (\fBirc_session_t\fP * session, const char * channel, const char * topic)"
.PP
Views or changes the channel topic. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP An initiated and connected session. 
.br
\fIchannel\fP A channel name to invite to. Must not be NULL. 
.br
\fItopic\fP A new topic to change. If NULL, the old topic will be returned, and topic won't changed.
.RE
.PP
\fBReturns:\fP
.RS 4
Return code 0 means success. Other value means error, the error code may be obtained through \fBirc_errno()\fP. Any error, generated by the IRC server, is available through \fBirc_callbacks_t::event_numeric\fP.
.RE
.PP
The \fBirc_cmd_topic()\fP is used to change or view the topic of a channel. The topic for \fIchannel\fP is returned if \fItopic\fP is NULL. If the \fItopic\fP is not NULL, the topic for the \fIchannel\fP will be changed. Note that, depending on \fI+t\fP channel mode, you may be required to be a channel operator to change the channel topic.
.PP
If the command succeed, the IRC server will generate a RPL_NOTOPIC or RPL_TOPIC message, containing either old or changed topic. Also the IRC server can (but not have to) generate the non-RFC RPL_TOPIC_EXTRA message, containing the nick of person, who's changed the topic, and the time of latest topic change.
.PP
Possible error responces for this command from the RFC1459:
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NEEDMOREPARAMS\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_CHANOPRIVSNEEDED\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_ERR_NOTONCHANNEL\fP
.PP
.PP
And the topic information is returned using one of following reply codes:
.IP "\(bu" 2
\fBLIBIRC_RFC_RPL_NOTOPIC\fP
.IP "\(bu" 2
\fBLIBIRC_RFC_RPL_TOPIC\fP
.PP
.PP
\fBSee also:\fP
.RS 4
\fBirc_callbacks_t::event_topic\fP \fBirc_cmd_channel_mode\fP 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for libircclient from the source code.
